在前端開發時，經常需要和後端 API 進行溝通，傳遞資料並接收回應。而在這些操作中，為了確保數據的正確性和程式碼的穩定性，使用 TypeScript 來為 API 的請求和回應定義型別是一個非常好的做法。

今天的文章將透過簡單的範例，展示如何使用 TypeScript 來為 API 請求和回應定義型別，讓開發變得更加可靠和易於維護。

一、什麼是 API 請求與回應型別？

API 請求通常是指我們向伺服器發送的資料，而回應則是伺服器返回給我們的資料。使用 TypeScript，我們可以為這些資料定義具體的型別，確保在進行 API 操作時，傳入和接收的數據格式正確無誤。

範例情境：To Do List 應用程式

就以常見簡單的 To Do List 應用程式來做範例說明，通常我們需要通過 API 來取得任務列表、創建新任務和刪除現有任務。

二、為 API 的請求與回應定義型別

定義一些基本的型別，這些型別將用於描述 API 的請求和回應結構。

定義基本的 To Do 資料型別

首先，定義一個 Todo 型別，包含了任務的 id、title 和 completed 狀態。這樣我們在處理 API 回應時，可以確保這些欄位是正確的。

type Todo = {
  id: number;
  title: string;
  completed: boolean;
};

1. 定義取得任務列表的回應型別

當我們從 API 取得所有任務時，後端會回傳一個任務列表。因此，我們可以為回應定義一個型別：

type GetTodosResponse = Todo[];

這裡的 GetTodosResponse 是一個 Todo 陣列，表示我們將會接收到多個任務。

2. 定義創建新任務的請求與回應型別

在創建任務時，我們會向 API 發送請求，傳遞新任務的資料。這些資料可以是任務標題及其完成狀態。

type CreateTodoRequest = {
  title: string;
  completed: boolean;
};

而當任務創建成功後，API 會回傳新建任務的詳細資訊，因此我們也需要定義回應型別：

type CreateTodoResponse = Todo;

3. 定義刪除任務的請求與回應型別

刪除任務時，我們通常只需要提供任務的 id，因此可以這樣定義請求型別：

type DeleteTodoRequest = {
  id: number;
};

這時候 API 的回應可能只會告知操作是否成功，所以回應型別可以設為簡單的狀態訊息：

type DeleteTodoResponse = {
  success: boolean;
};

三、實際使用範例：整合 API 請求與型別

接下來，則是展示如何在實際程式碼中使用這些型別來與 API 進行互動。

1. 使用 Fetch 來取得任務列表

使用 fetch 函式來調用 API，並結合我們定義的型別來處理回應。

async function fetchTodos(): Promise<GetTodosResponse> {
  const response = await fetch('/api/todos');
  const data: GetTodosResponse = await response.json();
  return data;
}

在這裡，我指定了 fetchTodos 函式的回傳型別為 GetTodosResponse，這樣 TypeScript 就能協助確保 API 回應的資料結構符合預期。

2. 創建新任務

當想要創建新任務時，就需要將資料傳遞給 API，並處理回應。

async function createTodo(newTodo: CreateTodoRequest): Promise<CreateTodoResponse> {
  const response = await fetch('/api/todos', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(newTodo),
  });
  
  const data: CreateTodoResponse = await response.json();
  return data;
}

這裡我們使用了 CreateTodoRequest 來定義請求的型別，並使用 CreateTodoResponse 來定義回應的型別，這樣可以保證傳遞的資料和返回的資料都符合正確的結構。

3. 刪除任務

最後，來看看如何處理刪除任務的操作：

async function deleteTodo(id: number): Promise<DeleteTodoResponse> {
  const response = await fetch(`/api/todos/${id}`, {
    method: 'DELETE',
  });

  const data: DeleteTodoResponse = await response.json();
  return data;
}

在這裡，確保傳入的 id 是 number 型別，並且 API 回應的結果符合 DeleteTodoResponse 型別。

四、總結

通過使用 TypeScript，我們可以為 API 的請求和回應資料定義型別，這樣在與後端進行交互時，我們可以確保傳遞和接收的資料符合正確的格式。這不僅提升了程式碼的可靠性，還能幫助開發者更清晰地了解資料的流向和結構。這種方式非常適合大型應用程式開發，因為它能減少錯誤發生的機率，並讓程式碼更具可讀性和維護性。